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STEUATION TOO COKSUMER PROOUCTS 
REGISTRATION INFORMATIOM 

Please fill out the enclosed registration card and return 
It to us so that we may provide you with Information about 
updates and about new products. The serial number re- 
quested on the card Is the number printed on the corner of 

THE MILL. 

^mmi^ wM«%ANrr 

Stellatlon Two/Mlcroware warrants to the original user of 
this product that the physical media shall be free of 
defects resulting from faulty manufacture of the product or 
Its components for a period of thirty (30) days from the 
date of sale. STELLATION TW/MICROWARE MAKES NO WARRAhfTIES 
REGARDllNiG EITHER THE SATISFACTORY PERFORMANCE (e.g., MER- 
CHANTABILITY) OF THE SOFTWARE ENCODED ON THIS PRODUCT OR 
THE FITNESS OF THE SOFTWARE FOR ANY PARTICULAR PURPOSE. 
Defects covered by this Warranty shall be corrected either 
by repair or, at Stellatlon Two's election, by replacement. 
In the event of replacement, the replacement unit will be 
warranted for the remainder of the original thirty (30) day 
period or 10 days, whichever Is longer. 

Warranty/Service 
tnformtlon 

If your OS/9 BASIC 09 requires replacement, please return 
It to the dealer from whom It was purchased. If It Is not 
possible to return the disk to your dealer, you may send It 
directly to Stellatlon Two with proof of purchase. 

During warranty, we wll I replace or repair your OS/9 BASIC 
09 Software without charge. 

To return any Stellatlon Two product for service, please 
mall It post-paid. Package the card securely as we cannot 
be responsible for damage due to shipping. BE SWE TO 
enclose proof of purchase for warranty work. 

Mall post-paid to: 

Stellatlon Two 

P.O. Box 2342 

Santa Barbara, CA 93120 



REGARDING THIS MANUAL 

This manual Is written In the popular "speak to the reader" 
fashion rather than the traditional third person. We have 
attempted to present the material In an easily understood 
fashion, considering a wide range of readers* skill levels. 
Your critique will be appreciated. 

Conejo Computer Products 
3655 Thousand Oaks Boulevard, Suite 255 
West lake Village, C:A 91362 

The OS/9 User's Guide Is your primary source of "how-to" 
Information for the general OS/9 features, whereas this 
manual is primarily Intended to provide supplementary 
Information on features unique to the APPLE II adaptation 
of OS/9. You will benefit by reading the first few 
chapters of both before embarking on your first session 
with OS/9; In particular. It Is Important that you 
understand the concepts of the "tree-structured file 
directories" and the execution and data directories. 
Please disregard the discussion of the FORMAT command In 
the User's Guide for creating a backup disk and. Instead, 
refer to the procedure discussed In Chapter I. 



FOR TECHNICAL ASSISTANCE WITH PROBLEMS 

Please attempt to resolve the problem with your dealer's 
help. Should the need arise, contact Stellatlon Two for 
further assistance. 
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OPGRATION 

WELCOME to the world of OS/9-rhe most powerful and con- 
venient programming and computing environment ever made 
available for your APPLE II. 

Enclosed with your new software Is an OS/9 daughterboard. 
The daughterboard fits onto your MILL and serves as an 
address "«pplng device to reorganize APPLE memory space to 
conform to OS/9 requirements. 

Mote- To avoid bending pins or causing personal 'pln- 
prick- injury, please use enclosed tweezers to 

remove chips. 



n.pirrTlOMS ON IMSTALLATIOM OF tOUR OS/9 OMJOnERBOARD 
OIRECTIOMS ^ "^'7-_ ji (74LSH) with your oew OS/9 

^- S TviLsi^K ::Kr^a1n that the s«a.l notch c. 

the chip Is facing upwards In the same direction as all 

the other chips on the boards 

2. Remove Chip #2 (74LS367), located at the bottom right 

of the MUK 
3 Remove the green backing from the mounting tape adhered 
to the back of th^ daughterboard. 

A insert daughterboard pins Into lower right corner 
iXt of^he Mill (Where Chip #2 was orlglna^Hy In 
pUcel. Press mounting tape to the Ml 1 1 so that the 
daughterboard stays securely In place. 
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Your OS/9 assemblying Is no^ complete. AM that remains 
for you to do Is put the MM I In Its slot (any slot except 
0) and activate the switch. 

As you face the keyboard of your APPLE 11, the daughter- 
board switch pulled towards you will activate the Pascal 
Speed-up Kit and the Assembler APPLE DOS Environment. 
Pushed away from you, towards the back of your computer, 
the switch activates the OS/9 mode. When It Is necessary 
for you to flip the switch, we suggest you turn off the 
power and, as a precautionary measure, use the eraser end 
of a pencl I. 



OVERVIEW OF THE NVLE ADAPTATION OF OS/9 



Developed by Mlcroware Systems Corp. for 6809 computers, 
OS/9 was written to exploit the advanced capabi I Itles of 
the Motorola MC6809 Microprocessor, yielding a truly unique 
.and Innovative operating system. The BASIC 09 language 
I Ikewlse was developed to provide an extremely powerful 
and, moreover, convenient language which was previously 
Impractical with the older, less capable microprocessors. 
The advanced capabilities offered by OS/9 are yielding an 
Increasing set of appi Icatlons software which Is highly 
modular and extensible. 

THE MILL 6809 processor board made possible the marriage of 
this set of excellent software to the Apple II, resulting 
In a very large Improvement of the capabilities of this 
popular and Inexpensive computer. The adaptation of OS/9 
to the Apple 11 offers several features beyond those In- 
trinsic to OS/9 Itself: 

• Modern multi-tasking operating system 

• Multiple file directories simplify data 

organization 

• 6809 performs disk I/O, freeing the 6502 for I/O 

work 

• 6502 operates as an Independent I/O processor, 
controlling Apple compatible devices with or without 
Interrupt capability 

• All I/O Is Interrupt driven for optimal CPU utili- 
zation and operator conveniences such as type-ahead 
and printer spooling "In the background" 

• Time of day clock for multl-progrommlng and file a 
creation and modification date logging 
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I nter-processor 1 nterrupt for obta I n I ng exc I us 1 ve 
use of the memory/bus for time-crltlcal operations 

Memory optimally reorganized for OS/9 and for 16K 
RAM card. 

Modular software with extensive error checking 

Capabi I Ity for user-written peripheral device 
drivers 
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CHAPTER TOPICS 



Chapter Subject 



\ Getting started - booting, entering basic csomraands 

II Screens, 40 and 80 columns, lower case 

in The time-clock, multi-tasking, printer, 
serial ports 

IV Using BASIC 09 
Appendix A Other Available Software and Documentation 



CHAPTBt I 
GEiriNS STARTED 



RUNNING OS/9 FOR THE FIRST TtME 

Please follow these steps to "boot" OS/9 for the first 
time: 

1. Obtain a blank diskette on which a backup copy of 
the OS/9 system disk will be made. 

2. Boot-up APPLE DOS 3.3 and run the -COPYA" program. 
Answer the prompts from It and copy your OS/9 system 
disk to the blank disk. Label the new disk "OS/9 vO 
System Disk" and store the original In a safe place. 

3. Using the Introductory Instructions in the Opera- 
tions section. Install the "remapping ROM daughter- 
board" on THE MILL board. 

Kote : If you purchased THE MILL and OS/9 simultan- 
eously, the daughterboard will already be Installed. 

4. With the APPLE'S power off. Install THE MILL In any 
card slot except zero (OS/9 automatically determines 
the slot). 

5. Verify that the disk controller card for the DISK II 
drlve(s) Is In slot six. 

6. Place the OS/9 System disk into the first drive and 
turn on tt^e APPLE'S power. 

7. The message "OS/9 BOOT VI" should appear on the 
normal 40 column display. In a few seconds, "48K" 
or "64K" will appear In the upper left corner of the 
screen. The latter will appear only If your compu- 
ter has a Language Card or other 16K RAM card 
Instal ted. 

8. After a few seconds, a flashing cursor will appear. 
This Indicates that OS/9 has been successfully read 
from the disk Into memory and Is performing the 
Initialization procedure contained In the file 
"STARTUP." 

I-I 



9, Th 1 s procedure d 1 sp I ays a br I ef greet \ ng message 
enclosed by ••*"s, and runs a utility program which 
displays the memory utilization. 

10. Lastly, the message "SHELL" wl 1 1 appear and the 
co»wnand prompt: "0S9:" Including cursor. 

If all of the above steps were successful, skip the next 
section of troubleshooting. 



MHAT TO DO IF OS/9 MILL NOT BOOT 

The causes of a failure to boot are listed below In order 
of likelihood, most probable first: 

1. The daughter board may be Incorrectly Installed or 
the I.e. "chips" on It are reversed or backwards. 
Double check the setting of the switch. If you 
Insert the I.C. chips Incorrectly, there Is a small 
chance that the chip will have been permanently 
damaged and will need to be replaced. Also, check 
that THE MILL Is properly seated In the card slot 
connector. 

2. The disk may not have read properly. Repeat the 
COPYA program using the original disk, but reverse 
the drives this time. 

3. Perhaps there Is an Interface board installed which 
Is mecahnlcally or electrically Interfering. Do a 
vl sua I check for boards touch I ng each other. I f 
this Is not the case, remove all boards from the 
APPLE except THE MILL and the disk controller, then 
try the boot again. Lastly, remove the RAM or 
Language Card and restore the memory chip (If any) 
which was removed when that card was Installed (this 
reverts to a stock 48k machine). Try the boot 
again. 

4. We now may suspect that THE MILL or the daughter 
board Is defective. Do a thorough visual check for 
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loose chips or components which may have been broken 
In shipment. A good proof of the health of the 
board Is to remove the daughter board, replace the 
chip In the board whic was relocated to the daughter 
board, and via APPLE DOS, run one of the demonstra- 
tion prograqis for THE MILL which are available at 
your dealer. If you have purchased the PASCAL 
SPEED-UP KIT or the Assembler, try running them. If 
the board runs properly now, we know that the daugh- 
ter board Is defective or was Installed Incorrectly. 

5. If none of the above solves the fal lure to boot, 
please contact your dealer for assistance. Stella- 
tlon Two will gladly help In the event the problem 
cannot be solved by substitution of known-good 
components. 



GETTING ACQUAINTED MIIH OS/9 

If you are familiar with APPLE DOS, OS/9 will require a 
little time for you to get oriented to the philosophy of 
this new "boss" for your computer hardware, the operating 
system. OS/9 Is quite generalized and, once the initial 
familiarization Is accomplished, you will be delighted with 
the greater freedom now available. This section contains 
an overview of OS/9 as adapted for the APPLE II and a short 
walk-through of your first few commands to OS/9. 

The OS/9 system Is a modern operating system with capabil- 
ities usua 1 1 y found I n I arger ml n I -computer systems . The 
supplied User*s (kilde manual will give you a good overview 
of the concepts Involved In the multiple file directories 
and the generalized Input-output methods. You will benefit 
by reading the first few sections of the User's guide 
before attempting to use OS/9. After finishing this, 
follow along with the walk-through described below. 

After booting 05/9, the "0S9:" prompt appears on the 
screen. This prompt comes from a program called "SHELL" 
which responds to your commands to run other programs. 
You enter coiwnands In response to the 0S9: prompt. 
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REGM^DING DISKETTES 

This page should be skipped on first reading. The Informa- 
tion here Is required when you have booted and run OS/9 a 
few times using a verbatim copy of the OS/9 system disk 
(via COPA In APPLE DOS 3,3). 

The diskettes used by OS/9 are Identical to DOS 3,3 disks 
In terms of sectors per track, however, the directory and 
f I le structures are total ly dl fferent. Do not use OS/9 
disks with Apple DOS 3.3 commands except as a "read-only" 
disk for COPYA. OS/9 will not work with disks or disk 
controller for the 13 sector diskettes of OOS3.2 and 
earlier. 

The "FORMAT" command, described In the User's guide. Is NOT 
to be used In this APPLE version of OS/9. Because the 
APPLE disk does not conform to the defacto standards for 
disks (IBM 3740), you have been supplied an alternate util- 
ity program to prepare diskettes for use by OS/9. This 
program Is named "FORMATII" In the standard command direc- 
tory. FORMATII requires pre-formatted disks. We suggest 
that you boot APPLE DOS 3.3 and INIT several diskettes for 
use with OS/9. The steps to create a blank disk are: 
(requires two drives) 

1. Boot up APPLE DOS 3.3 

2. Using blank or scratch diskettes, type In an INIT 
command for several diskettes. 

After your first few exploratory sessions with OS/9, you 
will need to begin to use these diskettes. 

3. To make a diskette usable by OS/9, take a diskette 
prepared In step 2 and, after booting: 

Place the diskette In the second drive and type: 

FORMATII /Dl<return> 
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The FORMAT 1 1 program will prompt you to enter the name to 
be written on the disk (a "volume" name). Enter an appro- 
priate subject title for the purpose of the diskette (be 
brief). Write this name on the jacket label of the disk- 
ette. Try to keep two or three blank, pre-formatted and 
FORMATlMd diskettes available for use on a moment's 
notice. Mark these disks as "formatted for 0S9." 

Before we begin to enter commands, let's take a minute to 
learn how to use the special keyboard features. 



SPECIAL KEYS AVAILABLE 

The special characters you type to stop the screen scrol- 
ling, abort a program, etc., are not fixed keys; you nay 
change them to suite your preference. The utility program 
"TMODE" (see User's Guide) may be used to redefine one or 
more keys to be used instead of the predefined (default) 
keys. In addition to these keys, there are several special 
keys which allow you to use characters not normally avail- 
able on the APPLE keyboard. These "substitution" keys 
are: 

control-K yields a left bracket 

shIft-M yields a right bracket 

control -0 yields an underscore (note I) 

control-P yields a vertical bar (note I) 

control-V yields a left brace (note I) 

control-W yields a right brace (note I) 

right arrow yields a backslash 

Note 1: This key useful only with an 80 column display. 

The keys used for typographical error correction are: 

left-arrow backspace one column 
control-X delete current line 
control-A recall last line typed In 



Other special keys 
control-S 



"S" tops screen outpul^-press any non- 
special key to resume (I.e., space) 



control-X deletes the entire line 
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control-Q "Q"ult the current program (return to* 

coiimand node or to BASIC 09 »s debugger) 

escape signals end-of-flle for the keyboard 

These keys way be changed as desired via the T>4CX)E command. 

The "substitution" keys mentioned earlier cannot be changed 
with TMOOE* 

For now, just use left-arro** to backspace and control-X to 
delete a fouled-up line. 

ENTERING YOUR FIRST FEM CGM4AM>S 

Let's try a command now. Type In: 
CHX /D0/CMDS<cr> 
(the <cr> means pressing the "return" key) 

This moans: 

"change the execution directory to drive 0, directory 

04DS" 

This command tells OS/9 to select drive (known as 01 In 
APPLE DOS), and directory "CMOS" on that drive and use this 
as the "home base" for subsequent commands. Each command 
you type In Is actually the name of a small (executable) 
program to process the command. Thus, the number of coo>- 
mands aval I able Is easl ly expandable. As we will see 
later, you may tell OS/9 to load a specific command file 
Into memory and leave It there so that It need not be 
fetched from disk each time It Is used. You will want to 
do this with frequently used commands. Use the OIX command 
whenever you need to change the current disk directory for 
executable programs. YouM I also need to enter CHX If you 
change diskettes and wish OS/9 to use the execution direc- 
tory on the newly Inserted diskette. 



In addition to the execution directory, OS/9 allows for a 
separate "data" directory which Is used to store the files 
you work with which contain data rather than executable 
programs. To set the current data directory, type: 

CWO /D0<cr> 

which sets the data directory to drive and to the highest 
directory for the drive, or the "root" directory. In this 
directory are the names of all other directories and, 
perhaps, the names of soma files proper. 

Now let's enter a command to view the contents of the 
current data directory: 

DIR E<cr> 

which yields a length display. Compare the display to that 
in the User's Guide explanation of the DIR command. ^4ote 
the effect of the "E" In the command. To show the contents 
of the execution directory, we must be explicit and over- 
ride the "default" data directory which DIR showed us: 

DIR E /O0/CMDS<cr> 

This directory contains many commands you wll I be using 
later. Try the DIR command yourself, substituting the 
names Indicated by the previous DIR commands to be direc- 
tories (hint: they have a "D" In the "Attributes" column. 
With multiple directories you can see that organizing data 
by subject, job, or programming language Is quite easy with 
OS/9. The Idea of the separate data and execution direc- 
tories Is to control access to files and to keep the ac- 
counts for Company A separate from Company B (or an apple 
pie recipe separate from oranges In stock). 

NOTE: From here on, we will omit the <cr> reminder in the 

examples. 

Thus far, we have used only the DIR command. Here Is a 
utl l Ity coa«»and which I Ists text (ASCI l ) f 1 les on the 
screen: 
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LIST /D(a/SYS/ERRMSG 
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which moans; 

L\st drive 0, directory SYS, file ERRMSG to the screen. 

^n this case, the file (or pathname) Is a text file which 
contains the system error message look-up table. If you 
LIST a file containing binary data such as an executable 
file the screen will "go nuts" and display garbage. Use 
the Om E command and If a file's attributes Include an 
"E", you should not LIST It. 

Since the last CHD command specified the root (main) direc- 
tory on drive as the current directory, we could shorten 
up the last command to: 

LIST SYS/ERRMSG 

or even shorter If we change the default data directory: 

O^O /D0/SYS 
LIST ERRMSG 

In each of these commands, the LIST utility program was 
retrieved from the default execution directory which, via 
the earlier CHX command, we had set to /D0/CMOS. 

Do you recall that frequently used programs may be "loaded" 
Into memory to avoid having to fetch them from disk each 
time they are needed? Suppose you plan to use DIR often In 
the current work session so loading DIR would speed up 
things. ^^r& ^s a load cowmand to make DIR memory-resident 
rather than disk-resident: 

LOAD DIR 

This goes to the current execution directory <0«)S> and 
"locks" the DIR program Into memory. Now DlR commands will 
go directly to the copy of DIR In memory. 

To view the program "modules" currently loaded In 
use the "MDIR" (module directory) command: 

MDIR E 
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The user's guide explains this command. In the display 
from th I s conmand , you will see the roodu I es I nterna I to 
OS/9 which are always present after booting. Each of these 
modules Is explained In the System Programmer's manual 
(available from Stellatlon Two). Your APPLE OS/9 contains 
the following modules unique to the APPLE computer: 

AACIA controls keyboard and screen Input-output as 

well as miscellaneous peripheral device 
Interfaces. 
DISKII performs all read/write of diskettes via the 

6809. The 6502 processor does no disk I/O. 
TERM device descriptor for the keyboard/screen. 

It you have done the LOAD DIR conmand, you will see the DIR 
program In the list of memory modules displayed by the MDIR 
connand. It Is convenient to LOAD >©IR for most sessions. 

Ah, but how do we get a module OUT of memory If It Is no 
longer needed? Easy—UNLINK It. As shown In the display 
from the MDIR E command, a module has a "link" count which 
shows how many times It has been "claimed" by the system. 
You'll need to repeat the UNLINK <name> command If the link 
count Is 2 or greater. An easy way to do this Is to type 
In UNLir«C <name> once, then hit control A (recalls the last 
conmand) and <cr> repeatedly unltl the "module not found" 
error happens. You should not UNLINK a module which Is an 
I/O driver or device descriptor— reboot. 

You should now use the CHX, CHD, LIST, DIR, and MDIR com- 
mands to get the "feel" of OS/9 and the directories. If 
you get massages such as "ERROR 216" you are typing In non- 
exlstant file names or are In the wrong data directory, or 
have changed the execution directory with the OiX command 
and OS/9 cannot find the coiwnand you are trying to use. To 
get back to "square one", type: 



OIO /D0 and then 

OIX /D0/O«)S 

If you are terribly confused, RESET the APPLE and reboot. 
Pressing the RESET key (some Apples require a simultaneous 
CTRL key) will Instantly stop OS/9 and bring up the 6502 
monitor program on the 40 column display. From here, type 
the usual "6 ctrl-P" to reboot. 
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You wHI fK>tlce that error messages are output as numbers. 
These numbers are listed \n the back of the User's Guide, 
cross-referenced to the engllsh explanation. If you wish 
to have this explanation displayed on each error, type the 
command: 

PRI»4TERR 

This tells OS/9 to use the error number to find the appro- 
priate engllsh message In a file named "SYS/ERRMSG- which 
Is on drive 0. After using OS/9 a while, you wl 1 1 be able 
to recall the half-dozen or so common error numbers and 
will not need to wait for the engllsh message conversion. 
With experience, you will- find that YOU may change the 
ERRMSG file to display your error message Instead of the 
usual one. Ths Is useful for "turn-key" systems which need 
different human factors than those found In a development 
system. Note: To "undo" the PRINTERR command, you must 
reboot the system. 

Now would be a good time to read about the TMOOE command 
and experiment with It. Try turning on the screen pause 
which automatically stops every 24 lines (or whatever you 
define) during screen output. Remember not to use keys In 
the "substitute" category discussed earlier. Defining a 
commonly used key (such as <cr>) should be avoided. When 
entering new key codes, you will have to use the key-code 
chart on page 7 of the APPLE reference manual. Note that 
OS/9 prefers to use ASCII codes whose most significant bit 
Is zero rather than those In the APPLE manual which contain 
a one in that bit. When using TMOOE, Just subtract hex 80 
from all key codes In the APPLE manual. For example, 
control A In the manual Is hex 81, however, you would type 
In a "1" when using TMODE. 

If you have not already, experiment with the type-ahead 
feature. You may enter a command (or data to a program) at 
virtually any time since the keyboard Is scanned Indepen- 
dently by the 6502 processor's I/O package. The current 
version has about 80 characters of storage within module 
TERM for type-ahead. 



CHAPTER tl 
SCREEN DISPLAYS 



SPECIAL fEATlAES OF IME 40 COUMN DISPLAY 

OS/9 sends characters to the 40 column (standard) display 
via special software In the module AACIA which Interacts 
with Input-output support contained In the "6502 I/O pack- 
age" (more on this later). Unlike APPLE DOS, the char- 
acters you type are not sent directly to the display as you 
type them, but are first Interpreted by OS/9. Modules 
"TERM", "AACIA", and "SCF" are Involved with this. Because 
of th 1 s, you may type vl rtua 1 1 y any character w I thout 
disrupting the display. Indeed, If you use the TMOOE -EC«0 
option, a program may retrieve keystrokes without them 
being displayed. This Is useful for entering passwords or 
accept 1 ng 1 nput wh 1 ch Is to be processed w 1 thout be I ng 
displayed. 

The 40 column screen accepts the following special char- 
acters for control purposes; 

Hex Decimal Function ■ 



erase and home the cursor (upper left) 

set normal (whlte-on-black) video 

set Inverse video 

set flashing video 

home cursor, do not erase screen 

move cursor one column right, preserving 

screen 

move cursor one line down, preserving screen 



$0C 


12 


S0B 


13 


S16 


22 


$17 


23 


S19 


25 


(10 


28 



S0E 



15 



Again, these codes must come from a f I le or a program 
rather than the keyboard. 
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USING AM 80 COLUMN DISPLAY 



Wl+h power off. Install the VIDEX board (other manufac- 
turers* currently being verified) In slot 2 or 3 and pre- 
pare to connect the monitor video cable per the manual for 
the board, ^^ow boot up OS/9. For now, OS/9 will Initially 
"come-up" using the standard 40 column display so you will 
have to use that video cable for a mcxnont. After obtaining 
the usual OS/9: prompt, type: 



TMODE TYPE=3 -UPC 
TMODE TYPE=2 -UPC 



for slot 3, or 
for slot 2. 



If you now use the video on the 80 column display board's 
cabi e for your mon I tor you shou I d see the usua I OS/9: 
prompt and hitting <cr> should redisplay It on that moni- 
tor. Try the DIR E command In 80 columns.. .much better! 
As you gain experience, you will find that you may edit the 
above TMODE coiwnand Into the STARTUP file so that OS/9 will 
use the 80 column board automatically upon booting. 

Here are a few details on the use of the 80 column board 
for the technically oriented: OS/9 uses the on-board ROMs 
for display (output) purposes, however, the keyboard 
(Input) sections of the ROM are not used. (The Interrupt- 
drlven type-ahead philosophy prohibits any device service 
by "spinning In a loop." Those sections of the manual for 
the display board which discuss the effect of characters 
TYPED (vs. sent from a program) should be Ignored. For the 
VIDEX unit, the following summarizes the control characters 
recognized by the output sections of the ROM firmware: 



Hdx 



Decimal 



Function 



erase screen and home cursor 
erase from cursor to end of screen 
line feed, same column 
home cursor, no erase screen 
erase from cursor to end of line 

(the following must each be preceded by the "leadln" char- 
acter, hex IE = decimal 30: 



t0C 


12 


$17 


11 


$0A 


10 


J19 


25 


JIO 


29 



S00-$07 00-07 
SI0-S17 16-23 
$08-S0F 08-15 



low resolution graphics character set 

1 1 ne-draw I ng character set 

ASCII codes displayed In mnemonics 
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To position the cursor, send the following throe char- 
acters: 

30 X+32 V+32 

The following example, coded for BASIC 09, will Illustrate 
the cursor positioning function: 

DIM leadln, x,y: Integer 
PRINT CHRS(12); 
leadln=30 

FOR x=0 to 79 

FOR y=23 to STEP -I 

PRINT CHR$( leadln) ;CHRS(x+32);CHR$9y+32);"."; 

NEXT y 
NEXT X 

which print periods In all positions, bottom to top. 

A VlDEX demonstration Is Included in your package. In 
directory VIOEX, under the file name DEMO. This Is a 
BASlC/09 program. 



USING LOWER CASE 

(Note: Lower case operation requires an 80 column display 
board.) 

Your OS/9 supports the popu I ar "one-w 1 re" I ower case 
modification which allows you to shift between upper and 
lower case using the shift key exactly like a standard 
typewriter. The next paragraph describes how to Incorpor- 
ate this simple hardware modification If you have not 
already done so. When Incorporated, the 80 column display 
coupled with a good screen-oriented word processor (avail- 
able from Mlcroware) will provide a top-rate text proces- 
sing work station. 

A wire Is connected to the shift key and connected via a 
plug to the same I/O connector of the APPLE 11. On the 
APPLE II PLUS, a small clip such as the "E-Z Hook" may be 
attached (without soldering) to the rightmost, exposed. 
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vertical connector pin on the keyboard encoder circuit 
board, located beneath the keyboard. . txx>klng from the 
front'of the computer, this pin Is directly beneath the "»" 
key. On older Apples, the shift key wire Is attached to a 
solder pad located just under the shift key on the top 
(outside) of the computer. They key-cap must be temporar- 
lly removed to attach the wire. in either case, the other 
end of the wire connects to a Dual-ln-llne plug, pin 4 
(PB2). This plug Is then Inserted Into the Game I/O 
connector (same paddle plug). 



Another solution to the lower case problem Is the use of 
one of the popular replacements for the Applets keyboard 
encoder circuit board. 

When us 1 ng the "one-w 1 re" sh I ft key mod 1 f 1 cat 1 on , the 
keyboard operation Is as follows: 

Press and hold shift, then press esc (escape), then release 
esc and shift (sounds harder than It really Is). 

This turns on the effect of the shift key modification. To 
turn It off, repeat the above. Each "shlft-esc« reverses 
the on/off switch for the shift key modification. 

As long as the shlft-esc "switch" Is on, you use the 
keyboard Just as you would on a standard typewriter. To 
revert to the normal APPLE mode, just press shift-escape 
again. There Is one exception to the rule here: To set 
the "«", "'^r an<l "1" characters, you must press shlft-esc 
to leave lower case mode and type shift P for "«", etc. 
Fortunately, these characters are rarely used. 

While on the subject of keyboards, you may wish to review 
the earlier paragraph on "substitution" characters. Many 
of these are available only with the 80 column display. 
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GHAPTER III 
USING THE CUXK AND MULTI-TASKING 



We suggest that you skip this section until you have 
mastered the fundwentals of OS/9. The multi-tasking 
feature of OS/9 Is not dependent upon the Installation of a 
system tlme-of-day clock card. 

The OS/9 system really shines when you enable the tlroe-of- 
day clock. This term refers to the practice of keeping the 
processor within a computer (two processors In the case of 
APPLE 0$/9) busy at all times, even when waiting on the 
operator or a peripheral. The concept Is to have two or 
more programs or "processes" bidding for processor time. 
Your OS/9 system provides this feature and makes possible 
many time-saving capabilities for the user. To utilize 
multi-tasking, you will load a clock device descriptor 
module appropriate for your hardware and enable It. 

The following options are (at the publishing date) avail- 
able: 



1. 
2. 

3. 



You have no clock board for the APPLE: use NOCLK 

Westslde Electronics Superclock H (tm), slot 5: 
use WESCLK3 

Mountain Computer CPS multi-function card, slot 7: 
use 0»SCLK7 



To start the clock, simply type: 

LOAD <name> 
where <name> Is one of the names listed above. 
Then type: 

SETIME 

to run the set tlme-of-day utility which will prompt you to 
enter same. Now type: 



DATE T 
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which win display the date and time. Try this a few 
times. If you specified "NOCLK", the time Is maintained 
very roughly by a clelay loop In the 6502 processor's pro- 
gram within an Idle section. If you do have a clock board, 
the current date/t I roe Is obtaT ned from that board , I rre~ 
spectlve of the date time which you entered. In fact. If 
you reply with a <cr> to SETlME's prompt, the date/time 
wl M automatical ly be estabi I shed within one second <n/a 
for "WOCLK" ) . On the unusua I occasions the board • s date/ 
time Is Incorrect, use the software supplied by the manu- 
facturer to set the time within the logic l.C. on the 
board. This Is most often due to a battery failure. 

With the clock running now, type: 



SHOWTIME& 

and look on the video for the 40 column display. In the 
upper right corner you will see the date/time being dis- 
played and repeatedly updated. The command you entered 
told OS/9 to run SHOWTIME and (&) continue the current 
program (your SHELL command processor). If you now type: 

PROCS 

you will see a list of active procedures (tasks), one of 
which win be SHOWTIME. SHOWTIME tells OS/9 to put It -to 
sleep" for one second, then It executes and updates the- 
display, sleeps again, etc, etc. Try entering a few com- 
mands such as DIR and MDIR while SHOWTIME Is present. 
Since It Is a very simple program. Its execution time has 
little effect on your activities. Read about the SETPR 
command and try changing SHOWTIME's and your (SHELL) prior- 
ities, using PROCS to see the results. The higher the 
priority number, the more "rank" a process has when a fight 
for processor time occurs. A process at priority 255 Is 
akin to a 5-star general I For the adventuresome, read the 
User's guide on SLEEP and try It out. 

As you will see In the next section, the multi-tasking Is 
quite useful to do "background" work such as printing files 
on hard copy while simultaneously word-processing or pro- 
gramming, etc. A later section will also discuss the Tlme- 
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sharing monitor for adding additional terminals to your 
APPLE to allow multiple workstations. 

With the clock operating, OS/9 Is being Interrupted at 
approximately 100 millisecond Intervals by a program within 
the 6502 I/O package. Each of these Intervals Is called a 
"tick". The accuracy of these Intervals Is very rough due 
to the varying workload on the 6502. If you are using a 
clock board for the date/time, the actual tl»e-of-day will 
be as accurate as the board Is. If you have no clock board 
(NOCLK was used above), you may want to reenter the date/ 
time every hour or two (use the SETIME command). It Is 
very beneficial to keep the date correct since OS/9 auto- 
matically logs the creation and last modified date/time for 
all files and many language listings. 

Addition of a simple 60 Hz synchronizing signal will allow 
the date/time to be much more accurate with NOCLK. This 
addition also makes the clock "tick" rate much closer to 
100 milliseconds. This may be Important for applications 
making use of the FSSLEP function In assembly language. In 
most applications, this sync signal maintains the time 
accurately enough to eliminate the need for a clock board. 



USINS THE PRIMTER 

The printer Interface device descriptors (same jargon as 
used In the section on clocks) are, at the publishing date, 
as fol lows: 

EPSON I for an EPSON brand para I lei Interface to 

Centronics- 1 Ike printers. Including the MX80 
and MXlOO, for slot I. 

CPSLPT7 for a Centronics parallel Interface via the 

Mountain (Computer GPS Multifunction card, 
slot 7. 

As discussed later. It Is relatively easy to change the 
slot number (see SETOOM, below). Programmers may choose to 
adapt the supplied driver source code for other Interface 
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cards, perhaps using the Inter processor Interrupt descrlbea 
\n Chapter V. 

To access the printer for the first time after booting, 
type: 

LOAD <name> (one of the above names, as appropriate) 

This conwand need only be entered once and may be within 
the STARTUP file. 

Once loaded, to access the printer use the name "/P" to 
refer to the printer. For example: 

LIST A>0/SYS/ERRMSG >/P 

will send the Indicated file to the printer and return an 
0S9: prompt when the printing Is finished. The ">" Is the 
"I/O redirection" convention of OS/9 and In tis case means 
"Don't send output to the screen; send It to the printer." 
THE ">" signal applies to standard listing output "path". 
Error messages go on a path called the "error path" which 
may be redirected using "»" Instead of or In addition to 
the ">". For example: 

Like BASIC 09 MYPROGRAM >/P »/P 

will Invoke BASIC 09 with said file name and reroute 
standard listings as well as error messages to the printer. 
The program Itself never knows. This Is the Idea behind 
"transparent" I/O wherein you define I/O paths and devices 
when the program Is run, rather than when It Is written. 

Consider: 

DIR £ /D0/CMDS >/P& 

This command will send a directory listing to the printer 
and continue (the 4) the current program. 
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SIml larly: 

LIST /D0/SYS/ERRMSG >/P& 
will list said file name "In the background." 
To type an unwanted printout, type: 

KILL n 

where n Is the process number of the "process" doing the 
printout (e.g., LIST). 

r4ote: If the printer Is off-line and the abort will not 
take effect unti I It Is restored to on-l Ine and 
prints one more line. 

Do you recall how to see the list of processes (to find the 
"n" for LIST)? Hint: PROCS. 

To use the printer from BASIC/09 without using the ">" 
redirection scheme: 

DIM LP:IMTE6£R 

OPEN #LP,"/P" ,^^ 

PRINT #LP, "HELLO ON THE PRINTER" 
PRINT -HELLO ON THE CRT" 

or better style: 

DIM LP,OUTPATH: INTEGER 

INPUT "PRINTED REPORT (Y/N): ";YN$ 

IF YNS="Y" THEN 

OPEN #LP,"/P" 

OUTPATH-LP V REM assignment of true path number 
ELSE 

CMJTPATH'l V REM I Is screen unless redirected by SHELL 
ENDIF 
PRINT #OUTPATH, "HELLO ON WHATEVER DEVICE I" 

OS/9 allows you to have multiple printers; youMI just need 
a device descriptor and possibly a device driver for each. 
The second printer Is typically named "/PI" In the device 
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descriptor module. A single device driver, properly writ- 
ten, may drive multiple printers which use Identical Inter- 
face cards. The 100 millisecond clock tick of OS/9 and the 
FSSLEP system call (assembly language) allow a driver to be 
wr 1 tten comp I ete I y 1 ndependent of the 6502 I/O package as 
well as the OS/9 Itself. 



USING TME SERIAL RS-252 PORT 

This section describes the supplied support for the Moun- 
tain Computer CPS multifunction card's serial port. Other 
manufacturers' serial ports are not aval I able (as of the 
publishing date), however, then you may write your own 
given the Information In the System Programmer's manual and 
the section of the assembler manual which describes the 
6502 1/0 package. 

As supplied, the CPS serial port Is configured for asyn- 
chronous operation at 300 baud (bits per second), 8 bits 
per character, no parity. These parameters can be altered 
as described later. To use the port, these steps are 
suggested: 

1. Obtain the cable to connect the peripheral (CRT, 
modem, printer, plotter, etc.) from the manufacturer 
or fabricate It per the Instructions In the manual 
for the card. 

2. Ensure that Data Set Ready and Carrier Detect are 
strapped to +12 VDC or connected to a device off- 
line signal from the peripheral. OS/9 will not send 
or receive on the port If either of these signals 
are false (-12 VDC). 

3. Ensure that the CPS card's Clear to Send signal (an 
Input) Is connected to +12 VDC or connected to the 
peripheral's 'ready/busy signal which controls the 
acceptance of data from the 0*S card. If th 1 s 
signal goes false, the current character will be the 
last output until the signal again goes true. 
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4* Ensure that the card operates properly and Is able 
to successf u 1 1 y conroun I cate w 1 th the per 1 phera I 
using the manufacturer's test programs. 

Install the card In slot 7 for OS/9 (this Is alterable, 
descr 1 bed be t ow ) • Set up the dev 1 ce for the baud rate, 
b 1 ts per character , and par 1 1 y as descr 1 bed In the above 
paragraph. If the peripheral cannot achieve these para- 
meters, you will have to change them within the 6502 I/O 
package. This Is explained In the end of this section. 

Having accomplished the above, type: 

LOAD Tl 



which Is a file In the usual C>tt)S directory, 
command: 



^4ow the 



DIR >TI 

will send a directory listing to the serial port. If any 
of the Interface signals (carrier detect, data set ready, 
or clear to send) are false (-12 VDC), the transmission 
wilt be postponed untl I al I are true. Conversely, the 

command: 

LIST </TI 

will copy the Incoming serial data (If any) to the CRT 
until an end-of-flle Is received or you manually abort the 
operation via a control Q. 

In some applications, the peripheral may transmit a large 
number of characters and exceed the abl I Ity of OS/9 to 
dispose of them. For example: 

LIST </TI >/P 

will copy the serial Input data to the printer, however, 
the printer speed may be slow enough to cause an •k)verrun'' 
condition. OS/9 does buffer a 1 1 Input (and output), 
however, large speed mismatches will cause data loss and an 
error. In virtually any situation, lowering the line speed 



1 1 1-7 



(baud rate) will lessen speed ml snatch problews. Soi. 
applications way require a "protocol- which Is a program 1o 
accept data from /Tl In manageable blocks and send a brief 
acknowledging message to the sender to trigger anolher 
block. The subject of protocol Is quit© extensive and 
cannot be properly treated here. 

Fortunately, the clear to send line can be wired to the 
peripheral to solve the outbound data flow rate problem 
without protocol. Conversely, the peripheral can send the 
pause SETOOM coNmand*s PAUSE character to force OS/9 to 
momentarily cease transmission. The MULL«o parameter of 
SETOOH may solve certain Inteface problems. (SETOOM Is 
explained below.) Thus, In most applications, protocol Is 
not required for flow control. Critical applications may 
need a particular protocol to ensure error-free trans- 
mission. 

Most applications are simple enough to avoid complex 
Interface methods. Indeed, a printer or similar device Is 
easily Integrated. The addition of a second CRT (a CRT In 
the 1600-900 class) or hardcopy terminal Is readily accom- 
plished and greatly enhances the usefullness of the system. 
A letter quality printer with a serial Interface may also 
be attached. 



GHANSINS THE GPS CM«)*S SERIAL DATA RATE 

(Please refer to the CPS card manual and the data sheet for 

the SIgnetlcs 2651 Integrated circuit for full details) 

Two elght-bit variables are required to define the data 
rate and character size/parity for the serial port. These 
variables are not stored In the device descriptor module 
but rather are located within the 6502 I/O package. These 
variables are called "CPSI* and "CPS2* and their addresses 
are given In the appendix. As shown In table 6 of the 
SIgnetlcs data sheet, the baud rate may be defined by 
placing one of the following values In location "CPS2": 



1 1 1-8 



Baud Rate 


Hexadecimal Value 


no 


S32 


150 


S34 


300 


$35 


600 


S36 


1200 


$37 


2400 


$3A 


4800 


$30 


9600 


$3E 


19200 


$3F (see Signet 



other speeds) 

Likewise, the character size and parity go In location 
"CPSl" per the following (binary layout): 



number of stop bits: 



ill XX xxxx 
1 1 XX xxxx 



1 stop bit 

2 stop bits 



character length: 



xxxx I0XX 7 bits per character 
xxxx llxx 8 bits per character 
(5 and 6 also available) 



parity selection: 



xxxi9 xxxx 
XX0I xxxx 
XX II xxxx 



no parity 
odd parity 
even parity 



Calculate the desired value, perhaps referring to the data 
sheet, and place them In memory BEFORE first LOADMng Tl. 
The values may be stored using the OS/9 Debugger or as 
POKE'S from BASIC 09. Once /Tl Is used, changing these 
values will have no effect. Further details on the 6502 
I/O package control of the SIgnetlcs USART chip may be 
obtained by writing to Cone jo C^amputer Products, requesting 
same. Chapter V describes how to make the change permanent 
In the 6502 I/O package. 

Although not Implemented, the synchronous mode offered by 
Vhe SIgnetlcs may be utilized for communications circuits 
^uch as IBM Bl-sync, Its variants, and DEC'S DOCMP. There 
are currently no plans to provide this, subject to user 
demand. 
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THE SETOOM UTILITY 

ThU utility command Is supplied In the APPLE OS/9 package 
and Is not discussed In the User's guide. 

The purpose of this utility Is to allow a device descriptor 
module (DDM, described In the System Programmer's Manual) 
to be modified. The TMODE utility modifies a COPY of the 
device characteristics contained In the DOM. Thus, TMODE 
only works for a device for which a path has been estab- 
1 1 shed , e.g. , the devi ce 1 s "open" for read or wr I te. 
TMODE works for the screen and keyboard since they are most 
always open on paths to SHELL. Once a DOM has been modi- 
fied by SETDOM, programs which subsequently open a path to 
that device will use the newly modified characteristics. 



The SETDOM command Is 



(syntax) 



SETDDM <devlce-name> <argllst> 

where <devlce name> Is /P or /Tl, etc. and 

<argllst> Is optional and Identical to those discussed In 

the User's Guide for the TMODE command. 



Examples: 



SETDOM /P<cr> 



SETDOM /T1 NULL=50 



simply displays current settings for 

the printer 

-echo <cr> alters t%#o 

character I st 1 cs 



USING SETDOM TO ALTER AM INTERFACE CARD'S SUOT MMBER 

The command: 

SETDDM <devlce naroe> TYPE=n 

redefines the DOM's characteristic for slot number and card 
type, in the current version, the following possibilities 
exist: 
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Looking at the n In TYP£=n as eight binary bits: 
7654 3210 



xxMM MSSS 

Note: XX are reserved and unavailable where MMM Is the 
manufacturer or board type 
SSS Is the APPLE slot number, excluding zero 

Board type codes: 

EPSON Parallel printer f«4M = 000 

Mtn Computer's OPS parallel HMM = 00) 
(future growth) 

For example: 

SETDOM /P TYPE=02 

Is for modifying the supplied EPSONl DOM for 

slot 2. 
SETDDM /P TYPE=12 

Is for modifying CPSLPT7 for slot 2. 

The MMM code Is present to allow the 6502 to execute the 
appropriate code within the I/O package, given the Inter- 
face method. The on-board firmware cannot be used since It 
"loops on busy" which would have a severely detrimental 
effect on the ability of OS/9 to do concurrent I/O. At 
present, the clock DOM's need no MMM code In that the 
drivers are totally 6809 code. Clocks do need the SSS 
code, however. 

The 40 column display VIDEX board (device /TERM) need no 
MMM or SSS; the TMODE command Is used to set the slot and, 
since these devices have exclusive use of the (XKJT vector 
for the 6502, no MMM code Is needed. 
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^moBsmmm!^ 



^^ssm 



SAVING A HODIFIED DEVICE OESCRIPTGR MODULE (DOM) 

Case In point: modify EPSONI to reside In slot 7: 

LOAD EPSONI 

SETOOM /P TYPE=7 

(other SETDOM commands as required) 

SAVE /00/CMDS/TEMP EPSONI 

VERIFY <TEMP >EPS0N7 U 

ATTR EPS0N7 E 

DEL TEMP 

UNLINK EPSONI (repeat this until module not found error) 

LOAD EPS0N7 

DIR >/P 

From now on, use EPS0N7 rather than EPSON !• 

If the C^S card Is moved from slot 7, you must modify the 
DOMs for both CPSLPT7 and Tl to reflect the new slot 

number* 

Do not SETOOUM or SAVE or LOAD with a device currently In 
use! 
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CHAPTER !Y 
USING BASIC 09 



This section contains a brief outline on using BASIC 09 for 
the newcomer • P I ease spend a few hour s study I ng the 
BASIC 09 manual before reading this section. 

BASIC 09 Is In directory CMOS, file BASIC09. If you are 
going to be using It frequently, LOAD BASIC 09 Immediately 
after you boot the system. If you only type: 

BASIC09 

without previously doing the LOAD BASIC09, OS/9 will 
discard BASIC 09 when you type "BYE" to exit BASIC 09. 

The easiest way to learn BASIC 09 Is to study the manual 
and try Itl After you have typed In tt^e BASIC 09 from the 
SHELL (from the 0S9: prompt), you will see a B: prompt 
telling you that you are In the command level. Unlike 
other Basics, you cannot enter a direct command from the 
coamand level (I.e., "PRINT 2-t^2*«). You enter these In the 
debugger mode which has a 0: prompt. More on this later. 

From the B: prompt. If you hit <cr>, a directory of modules 
or procedures Is displayed. From command level you must 
specify which procedure you wish to alter and/or execute. 
On Initial entry, there are no modules. From here, you n^y 
wish to toad and run one of the supplied programs. To do 
this, place the diskette with the programs In, say, drive 
Dl and type: CHD /Dl/?, where ? Is the directory In which 
the program Is located. Now type: LOAD <program name>. 
Hitting <cr> now will show the procedures loaded. Type RUN 
<procedure name> to execute a selected procedure. 

Enter a oomoiand to Invoke the procedure editor: 

£ MINE means edit procedure named MINE 

The E : prompt means you are 1 n the ed I tor . Us 1 ng the 
BASIC 09 manual, enter a brief example program. YouMI 
need to spend a few minutes getting the hang of the editor. 
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To exit to the command level, type "Q<cr>". From the B; 
prompt, hit <cr> to see the procedure directory. Now run 
your program: RUN<cr>. If It "bombs out" with an error, 
you will be In the debugger with a "0:" prompt. Exit with 
another "Q<cr>" command, -Try creating a second procedure 
named "YOURS" with the editor. Now the procedure directory 
will show two names, with an "*" next to the last one run 
or edited. If you type *S^UN", this Is the one which will 
go. "RUN <name>" will run a specific one. 

To save a bunch or procedures, type: 

SAVE* <pathname> (defaults to the current data direc- 
tory) 

This dumps all procedures Into a single file. Now a KILL* 
will purge the procedure directory. To get them back, type 
LOAD <pathname> which will load 'em all back again. LOAD/ 
SAVE of specific ones Is explained In the manual. 

Now It's time to REALLY study the manual and the supplied 
BASIC 09 programs to get It down pat. 

After you've become a semi-expert, here are some of the 
common points of confusion: 

1. B: LIST <procname> >/P to get a pretty listing 

2. LOAD <pathname> then KILL <procedure> to reuse old 
modules. 



When Invoked from the shell via: 

BASIC 09 <pathname> 

pathname must match the name of one of 

cedures. 



the pro- 



4. If you get fancy with packed (complied) procedures, 
keep them In the execution directory. 

5. You'll make a lot of mistakes Involving variables' 
type. I.e., using a variable as If It were Integer 
(as path number variables) but forgetting to DIM IT: 

INTEGER. 
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6. If you do not use an 80 column display, your code 
will naturally tend to be awkward due to the tempta- 
tion to fit It onto the 40 column display. Also, 
lower case dramatically Improves legibility. 



7. If you run out of memory (error 207), use the MDIR 
command to see what modules are In memory. Don't 
forget that the she! I command: "BASIC09 <program> 
#nnK" may be needed If <program> will not fit In the 
default (#nnk omitted) memory size. Sometimes 
rebooting Is required to clean up a situation where 
I ots of modu I es have come and gone from memory , 
leaving many discontinuous regions. With experi- 
ence, you will learn how to avoid this. 



For applications requiring large amounts of memory, you may 
wish to obtain a product called RUNB which Is the run-time 
code of BASIC 09, minus the compiler, editor, and debugger. 
W I th th I s product, you may run comp 1 1 ed (and debugged ) 
code. RUNB Is approximately half the size of BASIC 09. 



The more you use BASIC 09, the more you will appreciate the 
speed with which you can get a program coded and running 
correctly. Not having a syntax error pop up 2-1/2 months 
after the program was "done" Is a real delight. You'll 
soon learn to develop reusable procedure modules so that, 
with time, the software library begins to build on Itself! 

Don • t forget the r I ght-arow key for mu 1 1 1 p I e statement 
tines. Many of the "substitution" keys mentioned In 
Chapter I are there for BASIC 09. 
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